/* mexHID.h
 * mexHID
 *
 * mexHID defines C "mex" routines for working with USB "Human Interface Devices" from Matlab.
 * mexHID can detect and configure HID devices and exchange data with them.
 *
 * mexHID.h specifies several mex-friendly functions for use by mexHID.c.  But it leaves the
 * implementation of these functions up to platform-specific code, defined elsewhere.
 *
 * By Benjamin Heasly, University of Pennsylvania, 22 Feb. 2010
 */

#ifndef _MEX_HID_H_
#define _MEX_HID_H_

#include "mex.h"

typedef double mexHIDDeviceID;
typedef double mexHIDElementCookie;

typedef struct mexHIDStructSlice {
	mxArray* mxStruct;
	int sliceIndex;
} mexHIDStructSlice;

typedef struct mexHIDArrayElement {
	mxArray* mx;
	int elementIndex;
} mexHIDArrayElement;

// global status for mexHID
int mexHIDInitialize(void);
int mexHIDTerminate(void);
void mexHIDExit(void);
int mexHIDIsInitialized(void);
mxArray* mexHIDGetAllOpenDevices(void);
void mexHIDStep(void);

// Inspect all attached HID devices
// Open, close, or inspect a single HID device
mxArray* mexHIDGetPropertiesForAllDevices(void);
mxArray* mexHIDGetPropertiesForDevice(mexHIDDeviceID deviceID);
mexHIDDeviceID mexHIDOpenDeviceMatchingProperties(const mxArray* propStruct);
int mexHIDCloseDevice(mexHIDDeviceID deviceID);

// Find devices that match given properties
// Get all or some properties of all or some device elements
// Set properties of device elements
mxArray* mexHIDFindDeviceElementsMatchingProperties(mexHIDDeviceID deviceID, const mxArray* propStruct);
mxArray* mexHIDGetAllPropertiesForAllDeviceElements(mexHIDDeviceID deviceID);
mxArray* mexHIDGetAllPropertiesForDeviceElements(mexHIDDeviceID deviceID, const mxArray* elementCookies);
mxArray* mexHIDGetPropertiesForDeviceElements(mexHIDDeviceID deviceID, const mxArray* elementCookies, const mxArray* propNames);
int	mexHIDSetPropertiesForDeviceElements(mexHIDDeviceID deviceID, const mxArray* elementCookies, const mxArray* propStruct);

// Read and write values of device elements (such as button states or voltages)
mxArray* mexHIDReadDeviceElementValues(mexHIDDeviceID deviceID, const mxArray* elementCookies);
int mexHIDWriteDeviceElementValues(mexHIDDeviceID deviceID, const mxArray* elementCookies, const mxArray* elementValues);

// build/replace/close/start/stop/reset a queue for certain device elements, with a given queue depth and a given MATLAB callback
//	the MATLAB callback should have the form: function myCallback(deviceID, data),
//  where data is an nX3 array with rows of the form [elementCookies, eventValue, eventTime]
int mexHIDOpenQueueForDeviceElementsWithMatlabCallbackAndDepth(mexHIDDeviceID deviceID, const mxArray* elementCookies, const mxArray* matlabCallback, int queueDepth);
int mexHIDCloseQueue(mexHIDDeviceID deviceID);
int mexHIDStartQueue(mexHIDDeviceID deviceID);
int mexHIDStopQueue(mexHIDDeviceID deviceID);
int mexHIDFlushQueue(mexHIDDeviceID deviceID);

#endif